home *** CD-ROM | disk | FTP | other *** search
/ NeXT Education Software Sampler 1992 Fall / NeXT Education Software Sampler 1992 Fall.iso / Programming / Classes / SocketClasses / doc / ascii / SktSocket.spec next >
Encoding:
Text File  |  1992-03-28  |  11.1 KB  |  380 lines
  1. Copyright 1992 by Nik A Gervae.  This is part of the documentation for
  2. the socket classes, which are licensed under the terms of the GNU General
  3. Public License as published by the Free Software Foundation.
  4.  
  5. The documented program and this documentation are distributed in the hope
  6. that it will be useful, but are provided "AS IS" AND WITHOUT ANY WARRANTY;
  7. without any express or implied warranty of MERCHANTABILITY or FITNESS FOR
  8. A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  9. Any use or distribution of the program and documentation must include
  10. appropriate copyrights to acknowledge Nik A. Gervae and the Free Software
  11. Foundation, Inc.
  12.  
  13. You should have received a copy of the GNU General Public License
  14. along with this documentation; if not, write to the Free Software
  15. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16.  
  17. ===============
  18.  
  19. SktSocket
  20.  
  21. INHERITS FROM    Object
  22.  
  23. DECLARED IN    SktSocket.h
  24.  
  25.  
  26.  
  27. CLASS DESCRIPTION
  28.  
  29. The SktSocket class, alone, provides an application with a clean object 
  30. interface to Berkeley UNIX stream socket connections, or together with 
  31. the SktSocketManager and SktSocketUser classes, provides an 
  32. application with the ability to act as a server for stream socket 
  33. connections.  The SktSocket class implements the actual input and output 
  34. on the socket (the distinction between SktSocket and socket parallels that 
  35. between Window and window).  The class specifications for 
  36. SktSocketManager and SktSocketUser provide more information on 
  37. using these three classes together.
  38.  
  39. An SktSocket object is automatically created and maintained by an 
  40. application's SktSocketManager object.  If you use an 
  41. SktSocketManager, you need never directly access the SktSockets.
  42.  
  43. These classes are intended to make sockets easy to use.  However, several 
  44. methods provide ways to access fairly low-level details of sockets which 
  45. may be useful in some situations.  For more information on sockets, see: 
  46. the related UNIX man pages; “An Introductory 4.3BSD Interprocess 
  47. Communication Tutorial” (reprinted in UNIX Programmer's 
  48. Supplementary Documents Volume 1, PS1:7); or, “An Advanced 4.3BSD 
  49. Interprocess Communication Tutorial” (reprinted in UNIX Programmer's 
  50. Supplementary Documents Volume 1, PS1:8).
  51.  
  52. See also: SktSocketManager, SktSocketUser
  53.  
  54.  
  55.  
  56. INSTANCE VARIABLES
  57.  
  58. Inherited from Object    Class    isa;
  59.  
  60. Declared in SktSocket    int            socketFd;
  61.             SktSocketManager    *manager;
  62.             SktSocketUser        *user;
  63.             char            *hostaddress;
  64.             char             *hostname
  65.             char            *outputQueue;
  66.             long int        queueLength;
  67.             NXZone            *zone;
  68.  
  69. SktSocketFd     The file descriptor of the SktSocket.
  70.  
  71. manager     The SktSocket object's SktSocketManager.
  72.  
  73. user         The SktSocket object's SktSocketUser.
  74.  
  75. hostaddress    The Internet address of the SktSocket's 
  76.         connected host (peer) in dot notation.
  77.  
  78. hostname     The hostname of the SktSocket's connected 
  79.         host.
  80.  
  81. outputQueue     Strings waiting to be sent to the connected 
  82.         host.
  83.  
  84. queueLength     The length, in bytes, of the output queue.
  85.  
  86. zone        The zone that the SktSocket was allocated 
  87.         from.
  88.  
  89.  
  90.  
  91. METHOD TYPES
  92.  
  93. Initializing and freeing SktSocket objects
  94. - initOnFd:WithManager:
  95. - initOnHostname:andPort:
  96. - initOnAddress:andPort:
  97. - setSocketOptions:
  98. - close
  99. - free
  100.  
  101. Retrieving SktSocket attributes
  102. - setUser:
  103. - user
  104. - manager
  105. - socketFd
  106. - hostaddress
  107. - hostname
  108.  
  109. Managing input and output
  110. - readInput
  111. - queueOutput:ofLength:
  112. - queueOutputString:
  113. - flushOutput
  114. - purgeOutput
  115.  
  116. INSTANCE METHODS
  117.  
  118.  
  119.  
  120. close
  121. - close
  122.  
  123. If the SktSocket has a manager, sends the SktSocketManager a 
  124. closeSocket: message to properly close the socket and remove all 
  125. references to the Socket object. This will result in free being sent to the 
  126. Socket, so you should not send a  free message after a close.  If the 
  127. SktSocket does not have a manager, this method simply sends self a free 
  128. message.  Returns nil.
  129.  
  130. See also:  - free
  131.  
  132.  
  133.  
  134. flushOutput
  135. - flushOutput
  136.  
  137. Writes all data in the output queue to the socket, thereby emptying the 
  138. queue.  Returns self, or nil if a memory reallocation fails.  If the return 
  139. value is nil, the SktSocket has become corrupt, and will crash the process 
  140. the next time it attempts to alter its output queue.  You should either free 
  141. the SktSocket or terminate the process.
  142.  
  143. See also: - queueOutput:, - purgeOutput
  144.  
  145.  
  146.  
  147. free
  148. - free
  149.  
  150. Purges all pending output, closes the socket, and deallocates the 
  151. SktSocket's memory.  You should not send this message yourself; use 
  152. close to correctly remove all references to the Socket in the associated 
  153. SktSocketManager.
  154.  
  155. See also: - close, - purgeOutput
  156.  
  157.  
  158.  
  159. hostaddress
  160. - (const char *)hostaddress
  161.  
  162. Returns the Internet address of the SktSocket's connected host in dot 
  163. notation.
  164.  
  165. See also: - hostname
  166.  
  167.  
  168.  
  169. hostname
  170. - (const char *)hostname
  171.  
  172. Returns the hostname of the SktSocket's connect host.
  173.  
  174. See also: - hostaddress
  175.  
  176.  
  177.  
  178. initOnAddress:andPort:
  179. - initOnAddress:(const char *)hostAddress andPort:(int)port
  180.  
  181. Attempts to connect to a server on the host at address hostAddress (a 
  182. string in Internet dot notation), port port.  The SktSocket's host address 
  183. and name are recorded.  If all goes well, returns self; otherwise it returns 
  184. nil.  Error messages are printed to stderr detailing the reason for failure.
  185.  
  186. This method also invokes setSocketOptions:, so that you may set file 
  187. descriptor flags in subclasses.  If setSocketOptions: returns nil, the 
  188. initialization is cancelled and returns nil.  SktSockets set the FNDELAY 
  189. file descriptor flag for themselves (see fcntl(2) in the UNIX manual 
  190. pages), so you needn't set that option.
  191.  
  192. This method, along with initOnHostname:andPort: and 
  193. initOnFd:withManager:, are the designated initializers for SktSocket 
  194. object.  Be sure to send one of these messages to super in any subclass 
  195. init... methods based on your needs.
  196.  
  197. See also: - initOnHostname:andPort:, - initOnFd:withManager:, 
  198. - setSocketOptions:, - setUser:
  199.  
  200.  
  201.  
  202. initOnFd:withManager:
  203. - init OnFd:(int)serviceSocketFd 
  204. withManager:(SktSocketManager *)aManager
  205.  
  206. Attempts to accept a connection to the sender's service socket with file 
  207. descriptor serviceSocketFd.  aManager must be of class 
  208. SktSocketManager or a subclass.  The SktSocket's host address and name 
  209. are recorded.  If all goes well, returns self; otherwise it returns nil.  If a 
  210. SktSocketManager is specified, it will log any error messages.
  211.  
  212. This method also invokes setSocketOptions:, so that you may set file 
  213. descriptor flags in subclasses.  If setSocketOptions: returns nil, the 
  214. initialization is cancelled and returns nil.  SktSockets set the FNDELAY 
  215. file descriptor flag for themselves (see fcntl(2) in the UNIX manual 
  216. pages), so you needn't set that option.
  217.  
  218. This method, along with initOnAddress:andPort: and 
  219. initOnHostname:andPort:, are the designated initializers for SktSocket 
  220. object.  Be sure to send one of these messages to super in any subclass 
  221. init... methods based on your needs.
  222.  
  223. See also:  - initOnAddress:andPort:, - initOnHostname:andPort:, 
  224. - setSocketOptions:, - setUser:
  225.  
  226.  
  227.  
  228. initOnHostname:andPort:
  229. - initOnHostname:(const char *)hostName andPort:(int)port
  230.  
  231. Attempts to connect to a server on host hostName at port port.  The 
  232. SktSocket's host address and name are recorded.  If all goes well, returns 
  233. self; otherwise it returns nil.  Error messages are printed to stderr 
  234. detailing the reason for failure.
  235.  
  236. This method also invokes setSockeOptions:, so that you may set file 
  237. descriptor flags in subclasses.  If setSocketOptions: returns nil, the 
  238. initialization is cancelled and returns nil.  SktSockets set the FNDELAY 
  239. file descriptor flag for themselves (see fcntl(2) in the UNIX manual 
  240. pages), so you needn't set that option.
  241.  
  242. This method, along with initOnAddress:andPort: and 
  243. initOnFd:withManager:, are the designated initializers for SktSocket 
  244. object.  Be sure to send one of these messages to super in any subclass 
  245. init... methods based on your needs.
  246.  
  247. See also:   - initOnAddress:andPort:, - initOnFd:withManager:, 
  248. - setSocketOptions:, - setUser:
  249.  
  250.  
  251.  
  252. manager
  253. - (SktSocketManager *)manager
  254.  
  255. Returns the SktSocketManager object coordinating this SktSocket with 
  256. others.  This is a handy test to find out if an SktSocket is running as a 
  257. server or a client.
  258.  
  259. See also: - initOnFd:withManager:
  260.  
  261.  
  262.  
  263. purgeOutput
  264. - purgeOutput
  265.  
  266. Empties the output queue without writing it to the socket.  Returns self, 
  267. or nil if a memory reallocation fails.  If the return value is nil, the 
  268. SktSocket has become corrupt, and will crash the process the next time it 
  269. attempts to alter its output queue.  You should either free the SktSocket 
  270. or terminate the process.
  271.  
  272. See also: - flushOutput, - free
  273.  
  274.  
  275.  
  276. queueOutput:ofLength:
  277. - queueOutput:(const char *)output ofLength:(long int)length
  278.  
  279. This method, usually invoked by the SktSocketUser, adds length bytes of 
  280. output to the end of the output queue, and updates the queue length.  
  281. Returns self, or nil if a memory reallocation fails.  If the return value is 
  282. nil, the SktSocket has become corrupt, and will crash the process the next 
  283. time it attempts to alter its output queue.  You should either free the 
  284. SktSocket or terminate the process.
  285.  
  286. See also: - flushOutput, - purgeOutput
  287.  
  288.  
  289.  
  290. queueOutputString:
  291. - queueOutputString:(const char *)aString
  292.  
  293. This method, usually invoked by the SktSocketUser, adds aString to the 
  294. end of the output queue, and updates the queue length.  It is provided as a 
  295. convenience, and is equivalent to sending
  296.  
  297. [myUser queueOutput:aString ofLength:strlen(aString)];
  298.  
  299. It is therefore not useful for having the null character at the end of the 
  300. string queued.  To do that, add 1 to aString's length and send 
  301. queueOutput:ofLength:.
  302.  
  303. Returns self, or nil if a memory reallocation fails.  If the return value is 
  304. nil, the SktSocket has become corrupt, and will crash the process the next 
  305. time it attempts to alter its output queue.  You should either free the 
  306. SktSocket or terminate the process.
  307.  
  308. See also: - flushOutput, - purgeOutput
  309.  
  310.  
  311.  
  312. readInput
  313. - readInput
  314.  
  315. This method, usually invoked by the SktSocket's manager, reads data 
  316. from the socket and has the SktSocket's user queue the input, sending it a 
  317. queueInput:ofLength: message.  Returns self.
  318.  
  319. See also: - queueInput:ofLength: (SktSocketUser)
  320.  
  321.  
  322.  
  323. setSocketOptions:
  324. - setSocketOptions:(int)fd
  325.  
  326. Does nothing and returns self.  You can override this method in 
  327. subclasses to set any options that you like on the socket's file descriptor.  
  328. Be sure to send setSocketOptions: to super in your own method.  If an 
  329. operation fails so that you don't want the SktSocket to be initialized, this 
  330. method should return nil.  An SktSocket sets the FNDELAY flag for 
  331. itself (see fcntl(2) in the UNIX manual pages), so you don't need to set 
  332. that one.
  333.  
  334. See also: - initOnFd:withManager:, - initOnAddress:andPort:, 
  335. - initOnHostname:andPort:, fcntl(2), setsockopt(2)
  336.  
  337.  
  338.  
  339. setUser:
  340. - setUser:aUser
  341.  
  342. Sets the SktSocket's user (which must be a subclass of SktSockerUser) to 
  343. aUser and returns the old user.  Also has the user set its socket to the 
  344. SktSocket.
  345.  
  346. See also: - initOn:manager:
  347.  
  348.  
  349.  
  350. socketFd
  351. - (int)socketFd
  352.  
  353. Returns the file descriptor of the SktSocket's socket.
  354.  
  355. See also: - initOn:manager:
  356.  
  357.  
  358.  
  359. user
  360. - user
  361.  
  362. Returns the the SktSocket's SktSocketUser object.
  363.  
  364. See also: - setUser:
  365.  
  366.  
  367.  
  368. CONSTANTS AND DEFINED TYPES
  369.  
  370.  
  371.  
  372. /*
  373.  * Minimum size of the output queue.  It gets shrunk
  374.  * to this if the content of the queue gets
  375.  * significantly smaller than this.
  376.  */
  377. #define OUTQSIZE  1024
  378.  
  379.  
  380.